home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / basic / qsam300.zip / QSAM300.DOC < prev    next >
Text File  |  1989-04-05  |  21KB  |  533 lines
  1.  
  2.                            A B-Tree Access Method
  3.                          for QuickBASIC Programmers.
  4.  
  5.                         QSAM 3.0 (C)1989 Cornel Huth
  6.  
  7.  
  8.         Feel free to use QSAM in any program of yours.  No registration
  9.         or payment is required.  If you want the source code send $20.00
  10.         to:
  11.  
  12.                             Cornel Huth
  13.                             ATTN: QSAM SOURCE
  14.                             6402 Ingram Rd.
  15.                             San Antonio, TX  78238
  16.  
  17.  
  18.             I will send you the latest version of QSAM source on
  19.             5¼" DS/DD IBM-readable diskette.  The source includes
  20.             the QSAM low-level stuff (written in MASM-compatible
  21.             assembly) and the QuickBASIC 4.0 I/O and interface.
  22.  
  23.  
  24.         -----------------------------------------------------------------
  25.         QSAM is a keyed-file system based on the b-tree sorting method.
  26.         In addition to finding any particular key and its associated
  27.         data record very quickly, QSAM allows sequential access to
  28.         the data file (not usually found in b-tree access programs).
  29.  
  30.         This program was originally created by Rick Grehan for Turbo-C.
  31.         He has submitted it to the public domain and I thank him for that
  32.         and the nice work he did on the very readable assembly code.
  33.  
  34.         What you should find in the QSAM package is the QSAM300.LIB,
  35.         QSAM300.DOC, and QSTEST.BAS and QSAM300.BI.
  36.  
  37.         Add QSAM300.LIB to your standard library if you like, and then
  38.         LINK /QU it into a QLB library for the environment.
  39.  
  40.                 C>lib yourstd.lib +qsam300.lib;
  41.  
  42.                 C>link /qu yourstd.lib,qb.qlb,nul,bqlb40.lib
  43.  
  44.  
  45.  
  46.  
  47.         -----------------------------------------------------------------
  48.         Interface summary:
  49.  
  50.         All QSAM routines are FUNCTIONs and return an integer code
  51.         which is detailed in Error Codes.  These must be DECLAREd.
  52.  
  53.          1)  Qcreatkf%(filename$,keylen%,kftype$)
  54.          2)  Qcreatdf%(filename$,reclen%)
  55.          3)  Qopenk%(filename$,fileno%)
  56.          4)  Qopend%(filename$,fileno%)
  57.          5)  Qcreatkr%(kfile%,dfile%,Qkey$,Qrec$)
  58.          6)  Qreadkr%(kfile%,dfile%,Qkey%,Qrec$)
  59.          7)  Qreadnkr%(kfile%,dfile%,Qkey$,Qrec$)
  60.          8)  Qinsertk%(kfile%,dfile%,Qkey$)
  61.          9)  Qwritedr%(dfile%,Qrec$)
  62.         10)  Qrewindk%(kfile%)
  63.         11)  Qdelk%(kfile%,Qkey$)
  64.         12)  Qdelkr%(kfile%,dfile%,Qkey$)
  65.         13)  Qclosek%(kfile%)
  66.         14)  Qclosed%(dfile%)
  67.         15)  Qfileattrk%(kfile%,keylen%,keys&,bfileno%,kftype$)
  68.         16)  Qfileattrd%(dfile%,reclen%,recs&,bfileno%,dftype$)
  69.  
  70.         -----------------------------------------------------------------
  71.         Interface detail:
  72.  
  73.          1)  Qcreatkf(filename$,keylen,kftype$)
  74.  
  75.              Create a new, empty key file.  If filename$ exists, its
  76.              header will be overwritten by null data.
  77.  
  78.              filename$ - string.   Pathname of key file to create.
  79.                          Any valid DOS drive/path/filename can be used.
  80.     
  81.              keylen    - integer.  Length of key for this key file.
  82.                          Valid range is 1 to 64 bytes.
  83.  
  84.              kftype$   - string.   For a sorting-only file, kftype$="O".
  85.                          For an indexing file, kftype$ = "K".  "O" is
  86.                          key-Only and has no associated data file (and
  87.                          data records).  It can be used as a sorting
  88.                          method.  For "K" files, you should create a
  89.                          data file.
  90.  
  91.              filename$ = "C:\HIST\AR89.KEY"
  92.              keylen = 16
  93.              kftype$ = "K"
  94.              stat = Qcreatkf(filename$,keylen,kftype$)
  95.  
  96.  
  97.          2)  Qcreatdf(filename$,reclen)
  98.  
  99.              Create a new data file.  If filename$ exists, its header
  100.              will be overwritten by null data.
  101.  
  102.              filename$ - string.   Pathname of data file to create.
  103.                          Any valid DOS drive/path/filename can be used.
  104.     
  105.              reclen    - integer.  Length of record for this data file.
  106.                          Valid range is 3 to 32767 bytes.
  107.  
  108.              filename$ = "C:\HIST\AR89.DAT"
  109.              reclen = 128
  110.              stat = Qcreatdf(filename$,reclen)
  111.  
  112.  
  113.          3)  Qopenk(filename$,fileno)
  114.  
  115.              Open an existing key file and associate it with fileno.
  116.              If the file is a key file, a data file will also need
  117.              to be opened.  You may have multiple index files opened for
  118.              a data file.  The fileno is an arbitrary number.  It does
  119.              not reflect either a BASIC handle nor a DOS handle.  It is,
  120.              however, used to reference the key file in any later operation.
  121.              QSAM uses the BASIC FREEFILE function to obtain an
  122.              available channel but hides this from the application.
  123.              Use Qfileattrk() for information on the key file.
  124.  
  125.              filename$ - string.   Pathname of existing key file.
  126.     
  127.              fileno    - integer.  Number to associate the key file
  128.                          with for future operations.  Valid range is
  129.                          0 to 9.
  130.  
  131.              filename$ = "C:\HIST\AR89."
  132.              ARKEY = 0
  133.              ARDAT = 0
  134.              stat = Qopenk(filename$+"KEY",ARKEY)
  135.              if stat = 0 then
  136.                 kfile = fileno
  137.                 stat = Qopend(filename$+"DAT",ARDAT)
  138.  
  139.  
  140.          4)  Qopend(filename$,fileno)
  141.  
  142.              Open an existing data file and associate it with fileno.
  143.              The fileno is an arbitrary number.  It does not reflect
  144.              either a BASIC handle nor a DOS handle.  It is, however,
  145.              used to reference the data file in any later operation.
  146.              Use Qfileattrd() for information on the data file.
  147.  
  148.              filename$ - string.   Pathname of existing data file.
  149.     
  150.              fileno    - integer.  Number to associate the data file
  151.                          with for future operations.  Valid range is
  152.                          0 to 9.
  153.  
  154.              {see Qopenk() for an example}
  155.  
  156.  
  157.          5)  Qcreatkr(kfile,dfile,Qkey$,Qrec$)
  158.  
  159.              Add the key, Qkey$, to the key file, kfile, and the data
  160.              record, Qrec$, to the data file, dfile.  Qkey$ must
  161.              not already exist.  QSAM is case-sensative so it is
  162.              recommended that keys be made upper-case (or lower) unless
  163.              there is a reason not to do this.
  164.  
  165.              kfile     - integer.  Number that was used as fileno in
  166.                          openk().
  167.  
  168.              dfile     - integer.  Number that was used as fileno in
  169.                          opend().
  170.  
  171.              Qkey$     - string.   Key to add to key file.
  172.  
  173.              Qrec$     - string.   Data record to add to the data file
  174.                          that is indexed by Qkey$.
  175.  
  176.              kfile = 0
  177.              dfile = 0
  178.              Qkey$ = acctid$ + acctxn$
  179.              Qrec$ = xaction$
  180.              stat = Qcreatkr(kfile,dfile,Qkey$,Qrec$)
  181.  
  182.  
  183.          6)  Qreadkr(kfile,dfile,Qkey$,Qrec$)
  184.  
  185.              Search for key, Qkey$, in kfile, and if found, retrieve
  186.              the data record from dfile, and place it in Qrec$.
  187.  
  188.              kfile     - integer.  Number that was used as fileno in
  189.                          openk().
  190.  
  191.              dfile     - integer.  Number that was used as fileno in
  192.                          opend().
  193.  
  194.              Qkey$     - string.   Key for which to search in key file.
  195.  
  196.              Qrec$     - string.   Returned data record associated with
  197.                          Qkey$.
  198.  
  199.              kfile = 0
  200.              dfile = 0
  201.              Qkey$ = acctid$ + acctxn$
  202.              stat = Qreadkr(kfile,dfile,Qkey$,Qrec$)
  203.  
  204.  
  205.          7)  Qreadnkr(kfile,dfile,Qkey$,Qrec$)
  206.  
  207.              Retrieve the next ordered key in kfile, placing it in Qkey$,
  208.              and place its data record from dfile into Qrec$.  This
  209.              function allows for sequential processing